Quarto for the curious


Tom Mock, RStudio PBC

 rstd.io/quarto-curious

2022-07-27

You are sneaky!

We don’t talk about Quarto

We don’t talk about Quarto

A tweet by Alison Hill revealing her blogpost on Quarto. Over the weekend, I wrote up my notes about using and teaching Quarto, based on my experiences working with the development team for over a year. I think (hope?) it is safe to talk about it now

We don’t talk about Quarto

A tweet by Kelly Bodwin revealing her excitement about Quarto. Did I stay up until 6am before the first night of class converting all my R Markdown materials to @quarto_dev? Yes, yes I did. Do I regret it? No, I do not. It's pretty rad my dudes.

We don’t talk about Quarto

Others had more questions…

What is a “Quarto”?

What is a “Quarto”?1

Ok, but what IS Quarto®?

Ok, but what IS Quarto®?

Quarto® is an open-source scientific and technical publishing system built on Pandoc

How do I make a cocktail?

Image: Kobby Mendez

Crafting a cocktail

diagram of converting liquor, citrus, sugar into delicious cocktails

“Crafting” process for literate programming

“Crafting” process for literate programming

“Crafting” process for literate programming

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

diagram of converting a Jupyter notebook via pandoc into markdown and then into output formats

So what is Quarto?

A Quarto document i.e. a .qmd is a plain text file, like a .rmd, that can be rendered to many different formats

A screenshot of a Visual and Source Quarto document

Anatomy of a Quarto document

  • Metadata (YAML)
---
format: html
---
  • Code
```{r}
#| eval: true
library(dplyr)
mtcars %>% 
  group_by(cyl) %>%
  summarize(mean = mean(mpg), .groups = "drop")
```
# A tibble: 3 × 2
    cyl  mean
  <dbl> <dbl>
1     4  26.7
2     6  19.7
3     8  15.1
  • Text
# Heading 1
This is a sentence with some **bold text**, some *italic text* and an [image](image.png).

So what is Quarto?

Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into PDF/Word/HTML reports, books, websites, presentations and more!

A screenshot of a Visual and Source Quarto document

So what is Quarto?



Quarto is the next-generation of RMarkdown.

For everyone.

A brief history of knitr1

  • 2011-10-16: initial development - an engine for dynamic report generation with R

  • 2012-01-17: initial CRAN release

  • 50 CRAN releases in 10 years https://cran.r-project.org/src/contrib/Archive/knitr/

A brief history of rmarkdown

  • Initial experiment: knitr::pandoc() (2014)2

  • Matured as the rmarkdown package (2015)

Quarto - unification for RMarkdown

We learned from 10 years of literate programming with knitr + rmarkdown - Quarto is the continuation and unification of the best parts of RMarkdown.

diagram of converting a Quarto document via knitr/pandoc into markdown and then into output formats

RMarkdown and knitr are not going away, we’re still supporting it!

Quarto - extending RMarkdown for other languages

We are meeting Julia/Python users in their native language

diagram of converting a Quarto document via Jupyter/pandoc into markdown and then into output formats

Photo by zero take

roam in color

Comfort of your own workspace

Comfort of your own workspace

A screenshot of a Quarto document rendered inside RStudio

A screenshot of a Quarto document rendered inside JupyterLab

A screenshot of a Quarto document rendered inside VSCode

One install, batteries included

One install, “Batteries included”

  • Any language, same syntax and approach
Feature R Markdown Quarto
Basic Formats
Beamer
PowerPoint
HTML Slides

|
Advanced Layout

Many Quarto formats

Feature R Markdown Quarto
Cross References
Websites & Blogs
Books
Interactivity Shiny Documents Quarto Interactive Documents
Paged HTML pagedown Summer 2022
Journal Articles rticles Summer 2022
Dashboards flexdashboard Fall 2022

What to do with my existing .Rmd or .ipynb?

RMarkdown (and knitr) is not going away!

For some of you - nothing changes! Keep using RMarkdown and Jupyter.

However, most existing .rmd or .ipynb can be rendered as-is via Quarto or with some editing.

quarto render my-favorite.rmd --to html


Since Jupyter notebooks can either be treated as a linear document to be re-executed or output document there are additional options like: --execute

quarto render my-favorite.ipynb --to html --execute


In fact, Quarto can help convert back and forth between .qmd and .ipynb:

quarto convert --help

Usage:   quarto convert <input>

Description:

    Convert documents to alternate representations.

  Convert notebook to markdown:                  quarto convert mydocument.ipynb                   
  Convert markdown to notebook:                  quarto convert mydocument.qmd                     
  Convert notebook to markdown, writing to file: quarto convert mydocument.ipynb --output mydoc.qmd

Quarto comes out of the box with much better accessibility, better defaults, more options, and a much more consistent syntax.

What about for Data Science at Work?

  • Quarto can be used in RStudio Team today!
  • Quarto v1.0 comes pre-installed in RStudio Workbench 2022.07.0 and later. You can use Quarto in RStudio Workbench’s RStudio IDE, JupyterLab/Jupyter notebooks, or VSCode.
  • Quarto can be published and re-executed by RStudio Connect!

Cocktails vs Mixed Drinks

Quarto, crafted with love and care

Development of Quarto is sponsored by RStudio, PBC. The same core team works on both Quarto and R Markdown:

Here is the full contributors list. Quarto is open source and we welcome contributions in our github repository as well! https://github.com/quarto-dev/quarto-cli.

Want more?

Follow @RStudio, @quarto_pub or me @thomas_mock on Twitter to stay up to date!


rstudio::conf 2022

Web resources

The Questions

  • What does “Quarto” mean?
  • Why Quarto?
  • What about my favorite format(s)?

Why Quarto, when RMarkdown and Jupyter already exist?

  • Quarto is the “Next generation of RMarkdown”
  • but RMarkdown (and knitr) is not going away
  • And almost all the knowledge you’ve accumulated along the way is still applicable!

So let’s build up a mental model of what Quarto is and how it relates to RMarkdown and Jupyter…

rstd.io/quarto-curious by @thomas_mock